
\documentstyle[titlepage,twoside,verbatimfiles]{article}

\begin{document}

\pagestyle{headings}

\newcounter{NoteNum}
\def\resetNote{\setcounter{NoteNum}{0}}
\def\takeNote{\addtocounter{NoteNum}{1}(\theNoteNum)}
\def\sameNote{(\theNoteNum)}

\title{ 
{\huge
The OpenGL Utility Toolkit (GLUT) Programming Interface} \\
\vspace{.4in}
API Version 1}
\author{Mark J. Kilgard \\
{\em Silicon Graphics Inc.}}

\maketitle

\setcounter{page}{0}

\renewcommand{\thepage}{\roman{page}}

OpenGL is a trademark of Silicon Graphics, Inc.  X Window System is
a trademark of X Consortium, Inc.

The author has taken care in preparation of this documentation but makes no
expressed or implied warranty of any kind and assumes no 
responsibility for errors or omissions.  No liability is assumed
for incidental or consequential damages in connection with or arising
from the use of information or programs contained herein.

\vspace{.5in}

\begin{center}
Copyright \copyright 1994 Mark J. Kilgard.  All rights reserved.
\end{center}

\vspace{.5in}

All rights reserved.  No part of this documentation may be reproduced,
in any form or by any means, without permission in writing from the author.

\newpage

\tableofcontents

\cleardoublepage

\setcounter{page}{1}

\renewcommand{\thepage}{\arabic{page}}

\section{Introduction}

\def\Fortran{{\sc Fortran}}

The OpenGL Utility Toolkit (GLUT) is a programming interface with ANSI C and
\Fortran\ bindings for writing window system
independent OpenGL programs.  The toolkit supports the following functionality:
\begin{itemize}
\item Multiple windows for OpenGL rendering.
\item Callback driven event processing.
\item An `idle' routine and timers.
\item A simple, cascading pop-up menu facility.
\item Utility routines to generate various solid and wire frame objects.
\item Support for bitmap and stroke fonts.
\item Miscellaneous window management functions.
\end{itemize}
An ANSI C implementation of GLUT for the X Window System \cite{x92} has
been implemented.

This documentation serves as both a specification and a programming guide.
If you are interested in a brief introduction to programming with GLUT,
look for the introductory OpenGL column \cite{kilgard94c}
published in {\em The X Journal}.

The remainder of this section describes GLUT's design philosophy and usage model.
The subsequent sections specify the GLUT routines, grouped by functionality.
The final sections discuss usage hints, the \Fortran\ binding, and implementation issues.
Appendix A enumerates and annotates the logical programmer visible state maintained by GLUT.
Appendix B presents the ANSI C GLUT API via its header file.
Appendix C presents the \Fortran\ GLUT API via its header file.

\subsection{Background}

One of the major accomplishments in the specification of OpenGL \cite{segal92,arb92}
was the
isolation of window system dependencies from OpenGL's rendering model.
The result is that OpenGL is window system independent.

  Window system operations such as
the creation of a rendering window and the handling of window system
events are left to the native window system to define.
Necessary interactions between OpenGL and the window system such as creating
and binding an OpenGL context to
a window are described separately from the OpenGL specification in a
window system dependent specification.  For example, the GLX specification
\cite{karlton93}
describes the standard by which OpenGL interacts with the X Window System.

The predecessor to OpenGL is IRIS GL \cite{sgi91a,sgi91b}.
 Unlike OpenGL, IRIS GL {\em does}
specify how rendering windows are created and manipulated.  IRIS GL's
windowing interface is reasonably popular largely because it is simple
to use.  IRIS GL programmers can worry about graphics programming without
needing to be an expert in programming the native window system.
Experience also demonstrated IRIS GL's windowing interface was high-level
enough that it could be retargeted to different window systems.  Silicon
Graphics migrated from NeWS to the X Window System without any major
changes to IRIS GL's basic windowing interface.

Removing window system operations from OpenGL is a sound decision
because it allows the OpenGL graphics system to be retargeted to
various systems including powerful but expensive graphics
workstations as well as mass-production graphics systems like video
games, set-top boxes for interactive television, and PCs.

Unfortunately, the lack of a window system interface for OpenGL
is a gap in OpenGL's utility.  Learning native window system APIs
such as the X Window System's Xlib \cite{kilgard94a} or
Motif \cite{kilgard94b} can be daunting.
Even those familiar with native window system APIs need to
understand the interface that binds OpenGL to the native window system.
And when an OpenGL program is written using the native window system
interface, despite the portability of the program's OpenGL rendering
code, the program itself will be window system dependent.

Testing and documenting OpenGL's functionality lead to
the development of the {\tt tk} and {\tt aux} toolkits.  The {\tt aux}
toolkit is used in the examples found in the {\em OpenGL Programming Guide}
\cite{neider93}.
Unfortunately, {\tt aux} has numerous limitations and its utility is
largely limited to toy programs.  The {\tt tk} library has
more functionality than {\tt aux} but was developed in an {\em ad hoc}
fashion and still lacks much important functionality that IRIS GL
programmers expect, like pop-up menus.

GLUT is designed to fill the need for a window system independent
programming interface for OpenGL programs.  The interface is designed
to be simple yet still meet the needs of useful OpenGL programs.
Features from the IRIS GL, {\tt aux}, and {\tt tk} interfaces are
included to make it easy for programmers used to these interfaces
to develop programs for GLUT.

\subsection{Design Philosophy}

GLUT simplifies the implementation of programs using OpenGL rendering.
The GLUT application programming interface (API) requires very few routines
to display a graphics scene rendered using OpenGL.  The GLUT API (like the OpenGL
API) is stateful.  Most initial GLUT state is defined and the
initial state is reasonable for simple programs.

The GLUT routines also take relatively few parameters.
No pointers are returned.  The only pointers passed into GLUT are character pointers
to strings (all strings passed to GLUT are copied, not referenced)
and opaque font handles.

The GLUT API is (as much as reasonable) window system independent.  For
this reason, GLUT does not return {\em any} native window system handles,
pointers, or other data structures.  More subtle window system dependencies
such as reliance on window system dependent fonts is avoided by GLUT; instead,
GLUT supplies its own (limited) set of fonts. 

% Reasonable leeway
% is granted implementations of GLUT for various window systems.  For window
% system interactions that may require guidance in implementation, the phrase
% ``The intent is'' will be used in this specification to describe the spirit of
% the intended window system interaction.

For programming ease, GLUT provides a simple menu sub-API.  While the menuing
support is designed to be implemented as pop-up menus, GLUT permits window system
constraints to support the menu functionality in another manner (pull-down menus
for example).

Two of the most important pieces of GLUT state are the {\em current window}
and {\em current menu}.  Most window and menu routines affect the {\em
current window} or {\em menu} respectively.  Most callbacks implicitly
set the {\em current window} and/or {\em menu} to the appropriate
window and/or menu responsible for the callback.  GLUT is designed
so that a program with only a single window and/or menu will not need
to keep track of any window or menu identifiers.  This greatly
simplifies very simple GLUT programs.

GLUT is designed for simple to moderately complex programs focused on OpenGL
rendering.  GLUT implements its own event loop.  For this reason, mixing GLUT
with other APIs that demand their own event handling structure may be difficult.
The advantage of a builtin event dispatch loop is simplicity.

GLUT contains routines for rendering fonts and geometric shapes.  GLUT makes
no claims on the OpenGL display list name space.  For this reason, none of the
GLUT rendering routines use OpenGL display lists.  It is up to the GLUT programmer
to compile the output from GLUT rendering routines into display lists
if this is desired.

GLUT routines are logically organized into several sub-APIs according
to their functionality.  The sub-APIs are:
\begin{description}
\item[\em Initialization.]
Command line processing,
window system initialization, and initial window creation state are controlled
by these routines.
\item[\em Beginning Event Processing.]
This routine enters GLUT's event processing loop.  This routine never returns
and continuously calls GLUT callbacks as necessary.
\item[\em Window Management.]
These routines create and control GLUT windows.
\item[\em Menu Management.]
These routines create and control GLUT pop-up menus.
\item[\em Callback Registration.]
These routines register callbacks to be called by the GLUT event processing loop.
\item[\em Color Index Colormap Management.]
These routines allow the manipulation of color index colormaps for windows.
\item[\em State Retrieval.]
This routine allows programs to retrieve state from GLUT.
\item[\em Font Rendering.]
These routines allow rendering of stroke and bitmap fonts.
\item[\em Geometric Shape Rendering.]
These routines allow the rendering of 3D geometric shapes including spheres,
cones, icosahedrons, and teapots.
\end{description}

\subsection{Conventions}

GLUT window and screen coordinates are expressed in pixels.  The upper left hand
corner of the screen or a window is (0,0).  X coordinates increase in a
rightward direction; Y coordinates increase in a downward direction.
Note:  This is inconsistent with OpenGL's coordinate scheme that generally
considers the lower left hand coordinate of a window to be at (0,0) but is
consistent with most popular window systems.

Integer identifiers in GLUT begin with one, not zero.  So window identifiers,
menu identifiers, and menu item indexes are based from one, not zero.

In GLUT's ANSI C binding, for most routines, basic types ({\tt int},
{\tt char*}) are used as parameters.  In routines where the parameters
are directly passed to OpenGL routines, OpenGL types ({\tt GLfloat})
are used.

The header files for GLUT should be included in GLUT programs
with the following include directive:
\begin{verbatim}
#include <GL/glut.h>
\end{verbatim}

The ANSI C GLUT library archive is typically named {\tt libglut.a} on Unix
systems.  GLUT programs need to link with the system's OpenGL and GLUT libraries
(and any libraries these libraries potentially depend on).
A set of window system dependent libraries may also be necessary
for linking GLUT programs.  For example, programs using the X11 GLUT
implementation typically need to link with Xlib, the X extension
library, the X miscellaneous utilities library, and the math library.

\subsection{Terminology}

A number of terms are used in a GLUT-specific manner throughout this
document.  The GLUT meaning of these terms is independent of the
window system GLUT is implemented for.  Here are GLUT-specific
meanings for the following GLUT-specific terms:
\begin{description}
\item[\em Callback]  A programmer specified routine that can be
registered with GLUT to be called in response to a specific type
of event.  Also used to refer to a specific callback routine
being called.
\item[\em Display mode]  A set of OpenGL frame buffer capabilities
that can be attributed to a window.
\item[\em Idle]  A state when no window system events are received
for processing as callbacks and the idle callback if registered,
is called.
\item[\em Menu entry]  A menu item that the user can select to
trigger the menu callback for the menu entry's value.
\item[\em Menu item]  Either a menu entry or a sub-menu trigger.
\item[\em Pop]  The act of forcing a window to the top of the
stacking order for sibling windows.
\item[\em Pop-up menu]  A menu that can be set to appear when a specified
mouse button is pressed in a window.  A pop-menu consists of multiple
menu items.
\item[\em Push]  The act of forcing a window to the bottom of the
stacking order for sibling windows.
\item[\em Reshape]  The act of changing the size or shape of the window.
\item[\em Sub-menu]  A menu cascaded from some sub-menu trigger.
\item[\em Sub-menu trigger]  A menu item that the user can enter to
cascade another pop-up menu to select more menu choices.
\item[\em Subwindow]  A type of window that is the child window of
top-level window or other subwindow.  The drawing and visible region
of a subwindow is limited by its parent window.
\item[\em Timer]  A callback that can be scheduled to be called in
a specified interval of time.
\item[\em Top-level window]  A window that can be placed, moved, resized,
etc. independently from other top-level windows by the user.
Subwindows may reside within a top-level window.
\item[\em Window]  A rectangular area for OpenGL rendering.
\item[\em Window display state]  One of shown, hidden, or iconified.
A shown window is potentially visible on the screen (it may be obscured
by other windows and not actually visible); a hidden window will
never be visible; and iconified window is not visible but could
be made visible in response to some user action like clipping the
window's corresponding icon.
\item[\em Window system]  The broad notion of the window system
that refers to both the mechanism and policy of the window system.
For example, in the X Window System both the window manager and the
X server are integral to what GLUT considers the window system.
\end{description}

\section{Initialization}

Routines beginning with the {\tt glutInit}- prefix are used to initialize
GLUT state.  The primary initialization routine is {\tt glutInit} that
should only be called exactly once in a GLUT program.  No non-{\tt glutInit}- prefixed
GLUT or OpenGL routines should be called before {\tt glutInit}.

The other {\tt glutInit}- routines may be called before {\tt glutInit}.
The reason is these routines can be used to set default window initialization
state that might be modified by the command processing done in {\tt glutInit}.
For example, {\tt glutInitWindowSize(400, 400)} can be called before {\tt glutInit}
to indicate 400 by 400 is the program's default window size.  Though the GLUT
program can
still override this default using window size command line options processed by
{\tt glutInit}.

\subsection{glutInit}

{\tt glutInit} is used to initialize the GLUT library.

\subsubsection*{Usage}

\begin{verbatim}
void glutInit(int *argcp, char **argv);
\end{verbatim}

\begin{description}
\itemsep 0in
\item[\tt argcp] A pointer to the program's
{\em unmodified} {\tt argc} variable from {\tt main.}
Upon return, the value pointed to by {\tt argcp}
will be updated, because {\tt glutInit}
extracts any command line options intended for the GLUT library.

\item[\tt argv] The program's {\em unmodified} {\tt argv} variable from
{\tt main.} Like {\tt argcp,} the data for {\tt argv}
will be updated because {\tt glutInit}
extracts any command line options understood by the GLUT library.
\end{description}

\subsubsection*{Description}

{\tt glutInit} will initialize the GLUT library and negotiate a session with the window
system.  During this process, {\tt glutInit}
may cause the termination of the GLUT program with an error message to the user if GLUT
cannot be properly initialized.  Examples of this situation include the failure to
connect to the window system, the lack of window system support for OpenGL, and invalid
command line options.

The options parsed are window system dependent.

\subsubsection*{X Implementation Notes}

The X Window System specific options parsed by {\tt glutInit} are as follows:
\begin{description}
\item[\tt -display DISPLAY]
Specify the X server to connect to.  If not specified, the
value of the {\tt DISPLAY} environment variable is used.

\item[{\tt -geometry} {\em W}{\tt x}{\em H}{\tt +}{\em X}{\tt +}{\em Y}]
Determines where window's should be created on the screen.  The
parameter following {\tt -geometry} should be formatted as a standard X geometry specification.
The effect of using this option is to change the GLUT
{\em initial size} and {\em initial position} the same as if
{\tt glutInitWindowSize} or {\tt glutInitWindowPosition}
were called directly.

\item[\tt -iconic]
Requests all top-level windows be created in an iconic state.

\item[\tt -indirect]
Force the use of {\em indirect} OpenGL rendering contexts.

\item[\tt -direct]
Force the use of {\em direct}
OpenGL rendering contexts (not all GLX implementations support
direct rendering contexts).  A fatal error is generated if direct
rendering is not supported by the OpenGL implementation.

\item[\tt -gldebug]
After processing callbacks and/or events, check if there are any OpenGL
errors by calling {\tt glGetError}.  If an error is reported, print out
a warning by looking up the error code with {\tt gluErrorString}.  Using
this option is helpful in detecting OpenGL run-time errors.

\item[\tt -sync]
Enable synchronous X protocol behavior.  This option makes it easier
to track down potential X protocol errors.

\end{description}

\subsection{glutInitWindowPosition, glutInitWindowSize}

{\tt glutInitWindowPosition} and {\tt glutInitWindowSize} set the
{\em initial window position} and {\em size} respectively.

\subsubsection*{Usage}

\begin{verbatim}
void glutInitWindowSize(int width, int height);
void glutInitWindowPosition(int x, int y);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt width]
Width in pixels.
\item[\tt height]
Height in pixels.
\item[\tt x]
Window X location in pixels.
\item[\tt y]
Window Y location in pixels.
\end{description}

\subsubsection*{Description}

Windows created by {\tt glutCreateWindow} will be requested to be created
with the current {\em initial window position} and {\em size}.

The initial value of the {\em initial window position} GLUT state is
-1 and -1.  If either the X or Y component to the {\em initial
window position} is negative, the actual window position is left
to the window system to determine.
The initial value of the {\em initial window size} GLUT state is 300 by 300.
The {\em initial window size} components must be greater than zero.

The intent of the {\em initial window position} and {\em size} values is
to provide a suggestion to the window system for a window's initial size
and position.  The window system is not obligated to use this information.
Therefore GLUT programs should not assume the window was created at the
specified size or position.  A GLUT program should use the window's
reshape callback to determine the true size of the window.

\subsection{glutInitDisplayMode}

{\tt glutInitDisplayMode} set the {\em initial display mode}.

\subsubsection*{Usage}

\begin{verbatim}
void glutInitDisplayMode(GLenum mode);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt mode]
Display mode, normally the bitwise ORing of GLUT display mode bit masks.  See values
below.
\end{description}
\begin{description}
\itemsep 0in
\item[\tt GLUT\_RGBA]
Bit mask to select an RGBA mode window.  This is the default if neither {\tt GLUT\_RGBA}
nor {\tt GLUT\_INDEX} are specified.
\item[\tt GLUT\_RGB]
An alias for {\tt GLUT\_RGBA}.
\item[\tt GLUT\_INDEX]
Bit mask to select a color index mode window.  This overrides {\tt GLUT\_RGBA} if it is also
specified.
\item[\tt GLUT\_SINGLE]
Bit mask to select a single buffered window.  This is the default if neither {\tt GLUT\_DOUBLE}
or {\tt GLUT\_SINGLE} are specified.
\item[\tt GLUT\_DOUBLE]
Bit mask to select a double buffered window.  This overrides {\tt GLUT\_SINGLE} if it is also
specified.
\item[\tt GLUT\_ACCUM]
Bit mask to select a window with an accumulation buffer.
\item[\tt GLUT\_ALPHA]
Bit mask to select a window with an alpha component to the color buffer(s).
\item[\tt GLUT\_DEPTH]
Bit mask to select a window with a depth buffer.
\item[\tt GLUT\_STENCIL]
Bit mask to select a window with a stencil buffer.
\end{description}

\subsubsection*{Description}

The {\em initial display mode} is used when creating top-level windows and
subwindows to determine the OpenGL display mode for the to-be-created window.

\section{Beginning Event Processing}

After a GLUT program has done initial setup like creating windows and menus, GLUT
programs enter the GLUT event processing loop by calling {\tt glutMainLoop()}.

\subsection{glutMainLoop}

{\tt glutMainLoop} enters the GLUT event processing loop.

\subsubsection*{Usage}

\begin{verbatim}
void glutMainLoop(void);
\end{verbatim}
 
\subsubsection*{Description}

{\tt glutMainLoop} enters the GLUT event processing loop.
This routine should be called at most once in a GLUT program.  Once called, this routine
will never return.  It will call as necessary any callbacks that have been registered.

\section{Window Management}

GLUT supports two types of windows:  top-level windows and subwindows.
Both types support OpenGL rendering and GLUT callbacks.  There is a
single identifier space for both types of windows.

\subsection{glutCreateWindow}

{\tt glutCreateWindow} creates a top-level window.

\subsubsection*{Usage}
\begin{verbatim}
void glutCreateWindow(char *name);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt name]
ASCII character string for use as window name.
\end{description}

\subsubsection*{Description}
{\tt glutCreateWindow} creates a top-level window.  The {\tt name} will
be provided to the window system as the window's name.  The intent is that the
window system will label the window with the name.

Implicitly, the {\em current window} is set to the newly created window.

Each created window has a unique associated OpenGL context.  State changes to
a window's associated OpenGL context can be done immediately after the
window is created.

The {\em pending display state} of a window is initially for the window
to be shown.  But the window's {\em pending display state} is not actually
acted upon until {\tt glutMainLoop} is entered.  This means until {\tt glutMainLoop}
is called, rendering to a created window is ineffective because the window
can not yet be displayed.

The value returned is a unique integer identifier for the window.  The
range of allocated identifiers starts at one.

\subsubsection*{X Notes}

The proper X Inter-Client Communication Conventions Manual (ICCCM)
toplevel properties are established.
The {\tt WM\_COMMAND} property is only established for the first window created.

\subsection{glutCreateSubWindow}

{\tt glutCreateSubWindow} creates a subwindow of the {\em current window}.

\subsubsection*{Usage}
\begin{verbatim}
void glutCreateSubWindow(int x, int y, int width, int height);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt x]
Window X location in pixels relative to parent window's origin.
\item[\tt y]
Window Y location in pixels relative to parent window's origin.
\item[\tt width]
Width in pixels.
\item[\tt height]
Height in pixels.
\end{description}

\subsubsection*{Description}

{\tt glutCreateSubWindow} creates a subwindow of the {\em current window}
of size {\tt width} and {\tt height} at location {\tt x} and {\tt y}
within the {\em current window}.
Implicitly, the {\em current window} is set to the newly created subwindow.

Each created window has a unique associated OpenGL context.  State changes to
a window's associated OpenGL context can be done immediately after the
window is created.

The {\em pending display state} of a window is initially for the window
to be shown.  But the window's {\em pending display state} is not actually
acted upon until {\tt glutMainLoop} is entered.  This means until {\tt glutMainLoop}
is called, rendering to a created window is ineffective.
Subwindows can not be iconified.

Subwindows can be nested arbitrarily deep.

The value returned is a unique integer identifier for the window.  The
range of allocated identifiers starts at one.

\subsection{glutSetWindow, glutGetWindow}

{\tt glutSetWindow} sets the {\em current window}; {\tt glutGetWindow}
returns the identifier of the {\em current window}.

\subsubsection*{Usage}
\begin{verbatim}
void glutSetWindow(int win);
int glutGetWindow(void);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt win]
Handle of GLUT window to make the {\em current window}.
\end{description}

\subsubsection*{Description}

{\tt glutSetWindow} sets the {\em current window}; {\tt glutGetWindow}
returns the identifier of the {\em current window}.
If no windows exist or the previously {\em current window} was destroyed, {\tt glutGetWindow}
will return zero.

\subsection{glutDestroyWindow}

{\tt glutDestroyWindow} destroys the specified window.

\subsubsection*{Usage}
\begin{verbatim}
void glutDestroyWindow(int win);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt win]
Handle of GLUT window to destroy.
\end{description}

\subsubsection*{Description}

{\tt glutDestroyWindow} destroy the window specified by {\tt win} and the window's
associated OpenGL context and logical colormap (if the window is color index).  If {\tt win} was
the {\em current window}, the {\em current window} becomes
invalid ({\tt glutGetWindow} will return zero).

\subsection{glutPostRedisplay}

{\tt glutPostRedisplay} marks the {\em current window} as needing to be redisplayed.

\subsubsection*{Usage}
\begin{verbatim}
void glutPostRedisplay(void);
\end{verbatim}

\subsubsection*{Description}

Mark the {\em current window} as needing to be redisplayed.  The next time
through {\tt glutMainLoop}, the window's display callback will be called
to redisplay the window.  Multiple calls to {\tt glutPostRedisplay}
before the next display callback opportunity generates only a single
redisplay.

Logically, window damage notification for a window is treated as a
{\tt glutPostRedisplay} on the damaged window.

\subsection{glutSwapBuffers}

{\tt glutSwapBuffers} swaps the buffers of the {\em current window} if double buffered.

\subsubsection*{Usage}
\begin{verbatim}
void glutSwapBuffers(void);
\end{verbatim}

\subsubsection*{Description}

Performs a buffer swap on the {\em current window}.  Specifically, {\tt glutSwapBuffers}
promotes the contents of the back buffer of the {\em current window} to become the
contents of the front buffer.  The contents of the back buffer then
become undefined.  The update typically takes place during the vertical
retrace of the monitor, rather than immediately after {\tt glutSwapBuffers}
is called.

An implicit {\tt glFlush} is done by {\tt glutSwapBuffers} before it returns.
Subsequent OpenGL commands can be issued immediately after calling
{\tt glutSwapBuffers}, but are not executed until the buffer exchange
is completed.

If the window is not
double buffered, {\tt glutSwapBuffers} has no effect.

\subsection{glutPositionWindow}

{\tt glutPositionWindow} requests a change to the position of
the {\em current window}.

\subsubsection*{Usage}
\begin{verbatim}
void glutPositionWindow(int x, int y);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt x]
New X location of window in pixels.
\item[\tt y]
New Y location of window in pixels.
\end{description}

\subsubsection*{Description}

{\tt glutPositionWindow} requests a change in the position of
the {\em current window}.
For top-level windows, the {\tt x} and {\tt y} parameters are
pixel offsets from the screen origin.  For subwindows, the
{\tt x} and {\tt y} parameters are pixel offsets from the window's
parent window origin.

The {\tt glutPositionWindow} requests are not processed immediately.
The request is executed after returning to the main event loop.
This allows multiple {\tt glutPositionWindow} and {\tt glutReshapeWindow}
requests to the same window to be coalesced.

In the case of top-level windows, a {\tt glutPositionWindow} call
is considered only a request for positioning the window.
The window system is free to apply its own policies to top-level
window placement.  The intent is that top-level windows
should be repositioned according {\tt glutPositionWindow}'s parameters.

\subsection{glutReshapeWindow}

{\tt glutReshapeWindow} requests a change to the size of
the {\em current window}.

\subsubsection*{Usage}
\begin{verbatim}
void glutReshapeWindow(int width, int height);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt width]
New width of window in pixels.
\item[\tt height]
New height of window in pixels.
\end{description}

\subsubsection*{Description}

{\tt glutReshapeWindow} requests a change in the size of
the {\em current window}.
The {\tt width} and {\tt height} parameters are
size extents in pixels.

The {\tt glutReshapeWindow} requests are not processed immediately.
The request is executed after returning to the main event loop.
This allows multiple {\tt glutReshapeWindow} and {\tt glutPositionWindow}
requests to the same window to be coalesced.

In the case of top-level windows, a {\tt glutReshapeWindow} call
is considered only a request for sizing the window.
The window system is free to apply its own policies to top-level
window sizing.  The intent is that top-level windows
should be resized according {\tt glutReshapeWindow}'s parameters.

\subsection{glutPopWindow, glutPushWindow}

{\tt glutPopWindow} and {\tt glutPushWindow} change the stacking order
of the {\em current window} relative to its siblings.

\subsubsection*{Usage}
\begin{verbatim}
void glutPopWindow(void);
void glutPushWindow(void);
\end{verbatim}

\subsubsection*{Description}

{\tt glutPopWindow} and {\tt glutPushWindow} work on both top-level
windows and sub-windows.  The effect of pushing and popping windows
does not take place immediately.  Instead the push or pop is saved
for execution upon return to the GLUT event loop.  Subsequent
push or pop requests on a window replace the previously saved
request for that window.  The effect of pushing and popping
top-level windows is subject to the window system's policy for
restacking windows.

{\raggedright
\subsection{glutShowWindow, glutHideWindow, glutIconifyWindow}

{\tt glutShowWindow}}, {\tt glutHideWindow}, and {\tt glutIconifyWindow}
change the display status of the {\em current window}.

\subsubsection*{Usage}
\begin{verbatim}
void glutShowWindow(void);
void glutHideWindow(void);
void glutIconifyWindow(void);
\end{verbatim}

\subsubsection*{Description}

{\tt glutShowWindow} will show the {\em current window} (though
it may still not be visible).  {\tt glutHideWindow} will hide
the {\em current window}.  {\tt glutIconifyWindow} will iconify
a top-level window but GLUT prohibits iconification of a sub-window.
The effect of showing, hiding, and iconifying windows does not
take place immediately.  Instead the requests are saved
for execution upon return to the GLUT event loop.
Subsequent show, hide, or iconification requests on a window
replace the previously saved request for that window.  The effect of hiding,
showing, or iconifying top-level windows is subject to the window
system's policy for displaying windows.

\subsection{glutSetWindowTitle, glutSetIconTitle}

{\tt glutSetWindowTitle} and {\tt glutSetIconTitle} change
the window or icon title respectively of the current top-level window.

\subsubsection*{Usage}
\begin{verbatim}
void glutSetWindowTitle(char *name);
void glutSetIconTitle(char *name);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt name]
ASCII character string for the window or icon name to be set for the window.
\end{description}

\subsubsection*{Description}

These routines should only be called when the {\em current window}
is a top-level window.  Upon creation of a top-level window,
the window and icon names are determined by the {\tt name}
parameter to {\tt glutCreateWindow}.  Once created, {\tt glutSetWindowTitle}
and {\tt glutSetIconTitle} can change the window and icon names
respectively of top-level windows.  Each call requests the
window system change the title appropriately.  The policy by which
the window and icon name are displayed is window system dependent.

\section{Menu Management}

\subsection{glutCreateMenu}

{\tt glutCreateMenu} creates a new pop-up menu.

\subsubsection*{Usage}

\begin{verbatim}
int glutCreateMenu(void (*func)(int value));
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt func]
The callback function for the menu that is called when a menu
entry from the menu is selected.  The value passed to the callback
is determined by the value for the selected menu entry.
\end{description}

\subsubsection*{Description}

{\tt glutCreateMenu} creates a new pop-up menu and returns a unique small-integer
identifier.  The menu identifier range is separate from the window identifier range
so menu and window identifiers are not distinct.
Implicitly, the {\em current menu} is set to the newly created menu.

When the menu callback is called because a menu entry is selected for
the menu, the {\em current menu} will be implicitly set to the menu
with the selected entry before the callback is made.

\subsubsection*{X Implementation Notes}

If available, GLUT for X will take advantage of overlay planes
for implementing pop-up menus.  The use of overlay planes can
eliminate display callbacks when pop-up menus are deactivated.
The {\tt SERVER\_OVERLAY\_VISUALS} convention \cite{kilgard93} is used to
determine if overlay visuals are available.

\subsection{glutSetMenu, glutGetMenu}

{\tt glutSetMenu} sets the {\em current menu}; {\tt glutGetMenu} returns the
identifier of the {\em current menu}.

\subsubsection*{Usage}

\begin{verbatim}
void glutSetMenu(int menu);
int glutGetMenu(void);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt menu]
The identifier of the menu to make the {\em current menu}.
\end{description}

\subsubsection*{Description}

{\tt glutSetMenu} sets the {\em current menu}; {\tt glutGetMenu} returns the
identifier of the {\em current menu}.
If no menus exist or the previously {\em current menu} was destroyed,
{\tt glutGetMenu} returns zero.

\subsection{glutDestroyMenu}

{\tt glutDestroyMenu} destroys the specified menu.

\subsubsection*{Usage}

\begin{verbatim}
void glutDestroyMenu(int menu);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt menu]
The identifier of the menu to destroy.
\end{description}

\subsubsection*{Description}

{\tt glutDestroyMenu} destroys the specified menu by {\tt menu}.  If {\tt menu}
was the {\em current menu}, the {\em current menu} becomes invalid and
{\tt glutGetMenu} will return zero.

\subsection{glutAddMenuEntry}

{\tt glutAddMenuEntry} adds a menu entry to the bottom of the {\em current menu}.

\subsubsection*{Usage}
\begin{verbatim}
void glutAddMenuEntry(char *name, int value);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt name]
ASCII character string to display in the menu entry.
\item[\tt value]
Value to return to the menu's callback function if the menu entry is selected.
\end{description}

\subsubsection*{Description}

{\tt glutAddMenuEntry} adds a menu entry to the bottom of the {\em current menu}.
The string {\tt name} will be displayed for the newly added menu entry.
If the menu entry is selected by the user, the menu's callback will be called
passing {\tt value} as the callback's parameter.

\subsection{glutAddSubMenu}

{\tt glutAddSubMenu} adds a sub-menu trigger to the bottom of the {\em current menu}.

\subsubsection*{Usage}
\begin{verbatim}
void glutAddSubMenu(char *name, int menu);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt name]
ASCII character string to display in the menu item from which to cascade the sub-menu.
\item[\tt menu]
Identifier of the menu to cascade from this sub-menu menu item.
\end{description}

\subsubsection*{Description}

{\tt glutAddSubMenu} adds a sub-menu trigger to the bottom of the {\em current menu}.
The string {\tt name} will be displayed for the newly added sub-menu trigger.
If the sub-menu trigger is entered, the sub-menu numbered {\tt menu} will
be cascaded, allowing sub-menu menu items to be selected.

\subsection{glutChangeToMenuEntry}

{\tt glutChangeToMenuEntry} changes the specified menu item in the {\em current
menu} into a menu entry.

\subsubsection*{Usage}
\begin{verbatim}
void glutChangeToMenuEntry(int entry, char *name, int value);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt entry]
Index into the menu items of the {\em current menu} (1 is the topmost
menu item).
\item[\tt name]
ASCII character string to display in the menu entry.
\item[\tt value]
Value to return to the menu's callback function if the menu entry is selected.
\end{description}

\subsubsection*{Description}

{\tt glutChangeToMenuEntry} changes the specified menu entry in the {\em current
menu} into a menu entry.  The {\tt entry} parameter determines which menu
item should be changed, with one being the topmost item.  
{\tt entry} must be between 1 and {\tt glutGet(GLUT\_MENU\_NUM\_ITEMS)}
inclusive.
The menu item to
change does not have to be a menu entry already.  The string {\tt name}
will be displayed for the newly changed menu entry.  The {\tt value}
will be returned to the menu's callback if this menu entry is selected.

\subsection{glutChangeToSubMenu}

{\tt glutChangeToSubMenu} changes the specified menu item in the {\em
current menu} into a sub-menu trigger.

\subsubsection*{Usage}
\begin{verbatim}
void glutChangeToSubMenu(int entry, char *name, int menu);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt entry]
Index into the menu items of the {\em current menu} (1 is the topmost
menu item).
\item[\tt name]
ASCII character string to display in the menu item to cascade the sub-menu from.
\item[\tt menu]
Identifier of the menu to cascade from this sub-menu menu item.
\end{description}

\subsubsection*{Description}

{\tt glutChangeToSubMenu} changes the specified menu item in the {\em
current menu} into a sub-menu trigger.  The {\tt entry} parameter
determines which menu item should be changed, with one being the
topmost item.  
{\tt entry} must be between 1 and {\tt glutGet(GLUT\_MENU\_NUM\_ITEMS)}
inclusive.
The menu item to change does not have to be a sub-menu
trigger already.  The string {\tt name}
will be displayed for the newly changed sub-menu trigger.
The {\tt menu} identifier names the sub-menu to cascade from the
newly added sub-menu trigger.

\subsection{glutRemoveMenuItem}

{\tt glutRemoveMenuItem} remove the specified menu item.

\subsubsection*{Usage}
\begin{verbatim}
void glutRemoveMenuItem(int entry);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt entry]
Index into the menu items of the {\em current menu} (1 is the topmost
menu item).
\end{description}

\subsubsection*{Description}

{\tt glutRemoveMenuItem} remove the {\tt entry} menu item regardless of whether it
is a menu entry or sub-menu trigger.
{\tt entry} must be between 1 and {\tt glutGet(GLUT\_MENU\_NUM\_ITEMS)}
inclusive.
Menu items below the removed menu item are renumbered.

\subsection{glutAttachMenu, glutDetachMenu}

{\tt glutAttachMenu} attaches a mouse button for the {\em current window} to the identifier of
the {\em current menu}; {\tt glutDetachMenu} detaches an attached mouse button from the
{\em current window}.

\subsubsection*{Usage}
\begin{verbatim}
void glutAttachMenu(int button);
void glutDetachMenu(int button);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt button]
The button to attach a menu or detach a menu.
\end{description}

\subsubsection*{Description}

{\tt glutAttachMenu} attaches a mouse button for the {\em current window} to the identifier of
the {\em current menu}; {\tt glutDetachMenu} detaches an attached mouse button from the
{\em current window}.  By attaching a menu identifier to a button, the named menu
will be popped up when the user presses the specified button.
{\tt button} should be one of {\tt GLUT\_LEFT\_BUTTON}, {\tt GLUT\_MIDDLE\_BUTTON},
and {\tt GLUT\_RIGHT\_BUTTON}.  Note that the menu is attached to the button by
identifier, not by reference.

\section{Callback Registration}

GLUT supports a number of callbacks to respond to events.  There are
three types of callbacks:  window, menu, and global.   Window callbacks
indicate when to redisplay or reshape a window, when the visibility of
the window changes, and when input is available for the window.
The menu callback is set by the {\tt glutCreateMenu} call described already.
The global callbacks manage the passing of time and menu usage.

\subsection{glutDisplayFunc}

{\tt glutDisplayFunc} sets the display callback for the {\em current window}.

\subsubsection*{Usage}

\begin{verbatim}
void glutDisplayFunc(void (*func)(void));
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt func]
The new display callback function.
\end{description}

\subsubsection*{Description}

{\tt glutDisplayFunc} sets the display callback for the {\em current window}.
When GLUT determines that a window needs to be redisplayed, the display callback for the window
is called.  Before the callback, the {\em current window} is
set to the window needing to be redisplayed.  The display callback is
called with no parameters.  The entire window should be redisplayed
in response to the callback.

The redisplay state of a window is set.  Multiple posted redisplays
for a window are coalesced by GLUT to minimize the number of display
callbacks called.

Initially when a window is created, no display callback exists for
the window.  If a redisplay is posted for the window, it will simply
be discarded.  It is the responsibility of the programmer to install
a display callback for the window before the window is shown.  Passing {\tt NULL} to
{\tt glutDisplayFunc} will deregister the existing display callback.

\subsection{glutReshapeFunc}

{\tt glutReshapeFunc} sets the reshape callback for the {\em current window}.

\subsubsection*{Usage}
\begin{verbatim}
void glutReshapeFunc(void (*func)(int width, int height));
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt func]
The new reshape callback function.
\end{description}

\subsubsection*{Description}

{\tt glutReshapeFunc} sets the reshape callback for the {\em current window}.
When a window is created or reshaped, the reshape callback for the window
is triggered.  The {\tt width} and {\tt height} parameters of the callback
specify the new window size in pixels.  Before the callback, the {\em current
window} is set to the window that has been reshaped.

If a reshape callback is not registered for a window or {\tt NULL} is
passed to {\tt glutReshapeFunc} to deregister a previously registered
callback, the default reshape callback is used.  This default callback
will simply call {\tt glViewport(0,0,width,height)}.

When a top-level window is resized, subwindows are not resized.  It is
up to the GLUT program to manage the size and positions of subwindows
within a top-level window.  Still, reshape callbacks will be called for
sub-windows when their size is changed using {\tt glutReshapeWindow}.

\subsection{glutKeyboardFunc}

{\tt glutKeyboardFunc} sets the keyboard callback for the {\em current window}.

\subsubsection*{Usage}

\begin{verbatim}
void glutKeyboardFunc(void (*func)(unsigned char key,
                      int x, int y));
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt func]
The new keyboard callback function.
\end{description}

\subsubsection*{Description}

{\tt glutKeyboardFunc} sets the keyboard callback for the {\em current window}.
When a user types into the window, each key down event will generate a
keyboard callback.  The {\tt key} callback parameter is the ASCII character
for the depressed key.  The state of modifier keys such as Shift cannot be
determined directly; their only effect will be on the returned ASCII data.
The {\tt x} and {\tt y} callback
parameters indicate the mouse location in window relative coordinates
when the key was pressed.  When a new window is created, no keyboard
callback is initially registered and key strokes in the window are
ignored.  
Passing {\tt NULL} to {\tt glutKeyboardFunc} disables
the generation of keyboard callbacks.

\subsection{glutMouseFunc}

{\tt glutMouseFunc} sets the mouse callback for the {\em current window}.

\subsubsection*{Usage}

\begin{verbatim}
void glutMouseFunc(void (*func)(int button, int state, int x, int y));
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt func]
The new mouse callback function.
\end{description}

\subsubsection*{Description}

{\tt glutMouseFunc} sets the mouse callback for the {\em current window}.
When a user presses and releases mouse buttons in the window, each press
and each release generates a mouse callback.  The {\tt button} parameter
is one of {\tt GLUT\_LEFT\_BUTTON}, {\tt GLUT\_MIDDLE\_BUTTON}, or
{\tt GLUT\_RIGHT\_BUTTON}.  For systems with only two mouse buttons, it may
not be possible to generate {\tt GLUT\_MIDDLE\_BUTTON} callback.  For systems
with a single mouse button, it may only be possible to generate a
{\tt GLUT\_LEFT\_BUTTON} callback.  The {\tt state} parameter is either
{\tt GLUT\_UP} or {\tt GLUT\_DOWN} indicating whether the callback
was due to a release or press respectively.  The {\tt x} and {\tt y} callback
parameters indicate the window relative coordinates when the mouse
button state changed.  If a {\tt GLUT\_DOWN} callback for a specific
button is triggered, the program can assume a {\tt GLUT\_UP} callback for the 
same button will be generated (assuming the window still has a mouse
callback registered) when the mouse button is released even if
the mouse has moved outside the window.

If a menu is attached to a button for a window, mouse callbacks will
not be generated for that button.

Passing {\tt NULL} to {\tt glutMouseFunc} disables
the generation of mouse callbacks.

\subsection{glutMotionFunc, glutPassiveMotionFunc}

{\tt glutMotionFunc} and {\tt glutPassiveMotionFunc} set the motion and
passive motion callback respectively for the {\em current window}.

\subsubsection*{Usage}
\begin{verbatim}
void glutMotionFunc(void (*func)(int x, int y));
void glutPassiveMotionFunc(void (*func)(int x, int y));
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt func]
The new motion or passive motion callback function.
\end{description}

\subsubsection*{Description}

{\tt glutMotionFunc} and {\tt glutPassiveMotionFunc} set the motion and
passive motion callback respectively for the {\em current window}.
The motion callback for a window is called when the mouse moves
within the window while one or more mouse buttons are pressed.  The
passive motion callback for a window is called when the mouse moves
within the window while {\em no} mouse buttons are pressed.

The {\tt x} and {\tt y} callback parameters indicate the mouse location
in window relative coordinates.

Passing {\tt NULL} to {\tt glutMotionFunc} or {\tt glutPassiveMotionFunc}
disables the generation of the mouse or passive motion callback
respectively.

\subsection{glutVisibilityFunc}

{\tt glutVisibilityFunc} sets the visibility callback for the {\em
current window}.

\subsubsection*{Usage}
\begin{verbatim}
void glutVisibilityFunc(void (*func)(int state));
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt func]
The new visibility callback function.
\end{description}

\subsubsection*{Description}

{\tt glutVisibilityFunc} sets the visibility callback for the {\em
current window}.  The visibility callback for a window is called when
the visibility of a window changes.  The {\tt state} callback parameter
is either {\tt GLUT\_NOT\_VISIBLE} or {\tt GLUT\_VISIBLE} depending on
the current visibility of the window.  {\tt GLUT\_VISIBLE} does not
distinguish a window being totally versus partially visible.  {\tt GLUT\_NOT\_VISIBLE}
means no part of the window is visible, ie. until the window's visibility changes,
further rendering to the window is discarded.

Passing {\tt NULL} to {\tt glutVisibilityFunc}
disables the generation of the visibility callback.

If the visibility callback for a window is
disabled and later reenabled, the visibility status of the window is
undefined; any change in window visibility will be reported, that is
if you disable a visibility callback and reenable the callback, you
are guaranteed the next visibility change will be reported.

\subsection{glutEntryFunc}

{\tt glutEntryFunc} sets the mouse enter/leave callback for the {\em
current window}.

\subsubsection*{Usage}
\begin{verbatim}
void glutEntryFunc(void (*func)(int state));
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt func]
The new entry callback function.
\end{description}

\subsubsection*{Description}

{\tt glutEntryFunc} sets the mouse enter/leave callback for the {\em
current window}.  The {\tt state} callback parameter is either {\tt
GLUT\_LEFT} or {\tt GLUT\_ENTERED} depending on if the mouse pointer
has last left or entered the window.

Passing {\tt NULL} to {\tt glutEntryFunc}
disables the generation of the mouse enter/leave callback.

\subsection{glutMenuStateFunc}

{\tt glutMenuStateFunc} sets the global menu state callback.

\subsubsection*{Usage}
\begin{verbatim}
void glutMenuStateFunc(void (*func)(int state));
\end{verbatim}

\subsubsection*{Description}

{\tt glutMenuStateFunc} sets the global menu state callback so a GLUT
program can determine when a menu is in use or not.  When a menu state
callback is registered, it will be called with the value {\tt
GLUT\_MENU\_IN\_USE} for its {\tt value} parameter when pop-up menus are
in use by the user; and the callback will be called with the value {\tt
GLUT\_MENU\_NOT\_IN\_USE} for its {\tt value} parameter when pop-up menus
are no longer in use.  The {\tt func} parameter names the callback
function.  Other callbacks continue to operate (except user input
callbacks) when pop-up menus are in use so the menu state callback
allows a program to suspend animation or other taks when menus are in
use.  The cascading and unmapping of sub-menus from an initial pop-up
menu does not generate menu state callbacks.  There is
a single menu state callback for GLUT.

When the menu state callback is called, the {\em current menu} will be
set to the initial pop-up menu in both the {\tt GLUT\_MENU\_IN\_USE} and
{\tt GLUT\_MENU\_NOT\_IN\_USE} cases.  The {\em current window} will be
set to the window from which the initial menu was popped up from,
also in both cases.

Passing {\tt NULL} to {\tt glutMenuStateFunc}
disables the generation of the menu state callback.

\subsection{glutIdleFunc}

{\tt glutIdleFunc} sets the global idle callback.

\subsubsection*{Usage}
\begin{verbatim}
void glutIdleFunc(void (*func)(void));
\end{verbatim}

\subsubsection*{Description}

{\tt glutIdleFunc} sets the global idle callback to be {\tt func}
so a GLUT program
can perform background processing tasks or continuous animation when
window system events are not being received.  If enabled, the idle
callback is continuously called when events are not being
received.  The callback routine has no parameters.  The {\em current
window} and {\em current menu} will not be changed before the
idle callback.  Progams with multiple windows and/or menus should
explicitly set the {\em current window} and/or {\em current menu}
and not rely on its current setting.

The amount of computation and rendering done in an idle callback
should be minimized to avoid affecting the program's interactive
response.  In general, not more than a single frame of rendering
should be done in an idle callback.

Passing {\tt NULL} to {\tt glutIdleFunc}
disables the generation of the idle callback.

\subsection{glutTimerFunc}

{\tt glutTimerFunc} registers a timer callback to be triggered
in a specified number of milliseconds.

\subsubsection*{Usage}
\begin{verbatim}
void glutTimerFunc(unsigned long msecs,
                   void (*func)(int value), int value);
\end{verbatim}

\subsubsection*{Description}

{\tt glutTimerFunc} registers the timer callback {\tt func} to be triggered
in at least {\tt msecs} milliseconds.  The {\tt value} parameter to the timer
callback will be the value of the {\tt value} parameter to {\tt glutTimerFunc}.
Multiple timer callbacks at same or differing times may be registered
simultaneously.

The number of milliseconds is a lower bound on the time before the
callback is generated.  GLUT attempts to deliver the timer callback
as soon as possible after the expiration of the callback's time interval.

There is no support for canceling a registered callback.  Instead,
ignore a callback based on its {\tt value} parameter when it is triggered.

\section{Color Index Colormap Management}

OpenGL supports both RGBA and color index rendering.  The RGBA mode is generally
preferable to color index because more OpenGL rendering capabilities are
available and color index mode requires the hand loading of colormaps.

The GLUT color index routines are used to write and read entries in a window's
color index colormap.  Every GLUT color index window has its own logical color
index colormap.  The size of a window's colormap can be determined by calling
{\tt glutGet(GLUT\_WINDOW\_COLORMAP\_SIZE)}.

GLUT color index windows within a program can attempt to share colormap resources
by copying a single color index colormap to multiple windows using {\tt glutCopyColormap}.
If possible GLUT will attempt to share the actual colormap.  While copying
colormaps using {\tt glutCopyColormap} can potentially allow sharing of
physical colormap resources, logically each window has its own colormap.  So
changing a copied colormap of a window will force the duplication of the colormap.
For this reason, color index programs should generally load a single color index
colormap, copy it to all color index windows within the program, and then not
modify any colormap cells.

Use of multiple colormaps is likely to result in
colormap installation problems where some windows are
displayed with an incorrect colormap due to limitations on colormap
resources.

\subsection{glutSetColor}

{\tt glutSetColor} sets the color of a colormap entry.

\subsubsection*{Usage}
\begin{verbatim}
void glutSetColor(int ndx,
                  GLfloat red, GLfloat green, GLfloat blue);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt ndx]
Color cell index (starting at zero).
\item[\tt red]
Red intensity (clamped between 0.0 and 1.0 inclusive).
\item[\tt green]
Green intensity (clamped between 0.0 and 1.0 inclusive).
\item[\tt blue]
Blue intensity (clamped between 0.0 and 1.0 inclusive).
\end{description}

\subsubsection*{Description}

Sets the {\tt ndx} color index colormap entry of the {\em current window}'s logical
colormap with the color specified by {\tt red}, {\tt green}, and {\tt blue}.
The {\em current window} should be a color index window.
{\tt ndx} should be zero or greater and less than the total number of colormap entries
for the window.
If the {\em current window}'s colormap was copied by reference,
a {\tt glutSetColor} call will force the duplication of the colormap.

\subsection{glutGetColor}

{\tt glutGetColor} retrieves a red, green, or blue component for a given
color index colormap entry for the current window's logical colormap.

\subsubsection*{Usage}
\begin{verbatim}
GLfloat glutGetColor(int ndx, int component);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt ndx]
Color cell index (starting at zero).
\item[\tt component]
One of {\tt GLUT\_RED}, {\tt GLUT\_GREEN}, or {\tt GLUT\_BLUE}.
\end{description}

\subsubsection*{Description}

{\tt glutGetColor} retrieves a red, green, or blue component for a given
color index colormap entry for the {\em current window}'s logical colormap.
The {\em current window} should be a color index window.
{\tt ndx} should be zero or greater and less than the total number of colormap entries
for the window.
The value returned is a floating point value between 0.0 and 1.0 inclusive.

\subsection{glutCopyColormap}

{\tt glutCopyColormap} copies the logical
colormap from a specified window to the {\em current window}.

\subsubsection*{Usage}
\begin{verbatim}
void glutCopyColormap(int win);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt win]
The identifier of the window to copy the logical colormap from.
\end{description}

\subsubsection*{Description}

{\tt glutCopyColormap} copies (lazily if possible to promote sharing) the logical
colormap from a specified window to the current window.  Once a colormap has been
copied, avoid setting cells in the colormap with {\tt glutSetColor} since that
will force an actual copy of the colormap if it was previously copied by reference.

\section{State Retrieval}

GLUT maintains a considerable amount of programmer visible state.
Some (but not all) of this state may be directly retrieved.

\subsection{glutGet}

{\tt glutGet} retrieves simple GLUT state represented by integers.

\subsubsection*{Usage}
\begin{verbatim}
int glutGet(GLenum state);
\end{verbatim}
\begin{description}
\item[\tt state]  Name of state to retrieve.
\itemsep 0in
\end{description}

\begin{description}
\itemsep 0in
\item[\tt GLUT\_WINDOW\_X]
X location of the {\em current window}.
\item[\tt GLUT\_WINDOW\_Y]
Y location of the {\em current window}.
\item[\tt GLUT\_WINDOW\_WIDTH]
Width of the {\em current window}.
\item[\tt GLUT\_WINDOW\_HEIGHT]
Height of the {\em current window}.
\item[\tt GLUT\_WINDOW\_BUFFER\_SIZE]
Total number of bits for {\em current window}'s color buffer.
For an RGBA window, this is the sum of {\tt \tt GLUT\_WINDOW\_RED\_SIZE},
{\tt GLUT\_WINDOW\_GREEN\_SIZE}, {\tt GLUT\_WINDOW\_BLUE\_SIZE},
and {\tt GLUT\_WINDOW\_ALPHA\_SIZE}.  For color index windows, this
is the size of the color indexes.
\item[\tt GLUT\_WINDOW\_STENCIL\_SIZE]
Number of bits in the {\em current window}'s stencil buffer.
\item[\tt GLUT\_WINDOW\_DEPTH\_SIZE]
Number of bits in the {\em current window}'s depth buffer.
\item[\tt GLUT\_WINDOW\_RED\_SIZE]
Number of bits of red stored the {\em current window}'s color buffer.
Zero if the window is color index.
\item[\tt GLUT\_WINDOW\_GREEN\_SIZE]
Number of bits of green stored the {\em current window}'s color buffer.
Zero if the window is color index.
\item[\tt GLUT\_WINDOW\_BLUE\_SIZE]
Number of bits of blue stored the {\em current window}'s color buffer.
Zero if the window is color index.
\item[\tt GLUT\_WINDOW\_ALPHA\_SIZE]
Number of bits of alpha stored the {\em current window}'s color buffer.
Zero if the window is color index.
\item[\tt GLUT\_WINDOW\_ACCUM\_RED\_SIZE]
Number of bits of red stored in the {\em current window}'s accumulation buffer.
Zero if the window is color index.
\item[\tt GLUT\_WINDOW\_ACCUM\_GREEN\_SIZE]
Number of bits of green stored in the {\em current window}'s accumulation buffer.
Zero if the window is color index.
\item[\tt GLUT\_WINDOW\_ACCUM\_BLUE\_SIZE]
Number of bits of blue stored in the {\em current window}'s accumulation buffer.
Zero if the window is color index.
\item[\tt GLUT\_WINDOW\_ACCUM\_ALPHA\_SIZE]
Number of bits of alpha stored in the {\em current window}'s accumulation buffer.
Zero if the window is color index.
\item[\tt GLUT\_WINDOW\_DOUBLEBUFFER]
One if the {\em current window} is double buffered, zero otherwise.
\item[\tt GLUT\_WINDOW\_RGBA]
One if the {\em current window} is RGBA mode, zero otherwise (i.e., color index).
\item[\tt GLUT\_WINDOW\_COLORMAP\_SIZE]
Size of {\em current window}'s color index colormap; zero for RGBA color model windows.
\item[\tt GLUT\_SCREEN\_WIDTH]
Width of the screen in pixels.
Zero indicates the width is unknown or not available.
\item[\tt GLUT\_SCREEN\_HEIGHT]
Height of the screen in pixels.
Zero indicates the height is unknown or not available.
\item[\tt GLUT\_SCREEN\_WIDTH\_MM]
Width of the screen in millimeters.
Zero indicates the width is unknown or not available.
\item[\tt GLUT\_SCREEN\_HEIGHT\_MM]
Height of the screen in millimeters.
Zero indicates the height is unknown or not available.
\item[\tt GLUT\_MENU\_NUM\_ITEMS]
Number of menu items in the {\em current menu}.
\item[\tt GLUT\_DISPLAY\_MODE\_POSSIBLE]
Whether the {\em current display mode} is supported or not.
\item[\tt GLUT\_INIT\_DISPLAY\_MODE]
The {\em initial display mode} bit mask.
\item[\tt GLUT\_INIT\_WINDOW\_X]
The X value of the {\em initial window position}.
\item[\tt GLUT\_INIT\_WINDOW\_Y]
The Y value of the {\em initial window position}.
\item[\tt GLUT\_INIT\_WINDOW\_WIDTH]
The width value of the {\em initial window size}.
\item[\tt GLUT\_INIT\_WINDOW\_HEIGHT]
The height value of the {\em initial window size}.
\end{description}

\subsubsection*{Description}

{\tt glutGet} retrieves simple GLUT state represented by integers.
The {\tt state} parameter determines what type of state to
return.  GLUT state names beginning with {\tt GLUT\_WINDOW\_}
return state for the {\em current window}.  GLUT state names beginning
with {\tt GLUT\_MENU\_} return state for the {\em current menu}.
Other GLUT state names return global state.
Requesting state for an invalid GLUT state name returns negative one.

\section{Font Rendering}

GLUT supports two type of font rendering:  stroke fonts,
meaning each glyph is generated as geometry
composed of lines; and bitmap fonts, where each character
is a bitmap generated with {\tt glBitmap}.  Stroke fonts have
the advantage that because they are geometry, they can
be arbitrarily scale and rendered.  Bitmap fonts are
less flexible since they are rendered as bitmaps but are
usually faster than stroke fonts.

\subsection{glutBitmapCharacter}

{\tt glutBitmapCharacter} renders a bitmap character using OpenGL.

\subsubsection*{Usage}
\begin{verbatim}
void glutBitmapCharacter(void *font, int character);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt font]
Bitmap font to use.
\item[\tt character]
Character to render (not confined to 8 bits).
\end{description}

\subsubsection*{Description}

Without using any display lists, {\tt glutBitmapCharacter} renders the {\tt character}
in the named bitmap {\tt font}.  The available fonts are:
\begin{description}
\item[{\tt GLUT\_BITMAP\_8\_BY\_13}]
A fixed width font with every character fitting in an 8 by 13 pixel
rectangle.  The exact bitmaps to be used is defined by the standard X glyph
bitmaps for the X font named:

{\tt -misc-fixed-medium-r-normal--13-120-75-75-C-80-iso8859-1}

\item[{\tt GLUT\_BITMAP\_9\_BY\_15}]
A fixed width font with every character fitting in an 9 by 15 pixel
rectangle.  The exact bitmaps to be used is defined by the standard X glyph
bitmaps for the X font named:

{\tt -misc-fixed-medium-r-normal--15-140-75-75-C-90-iso8859-1}

\item[{\tt GLUT\_BITMAP\_TIMES\_ROMAN\_10}]
A 10-point proportional spaced
Times Roman font.  The exact bitmaps to be used is defined by the
standard X glyph bitmaps for the X font named:

{\tt -adobe-times-medium-r-normal--10-100-75-75-p-54-iso8859-1}

\item[{\tt GLUT\_BITMAP\_TIMES\_ROMAN\_24}]
A 24-point proportional spaced
Times Roman font.  The exact bitmaps to be used is defined by the
standard X glyph bitmaps for the X font named:

{\tt -adobe-times-medium-r-normal--24-240-75-75-p-124-iso8859-1}

\end{description}
Rendering a nonexistent character has no effect.  {\tt glutBitmapCharacter} automatically
sets the OpenGL unpack pixel storage modes it needs appropriately and saves and restores
the previous modes before returning.  The generated call to {\tt glBitmap} will
adjust the current raster position based on the width of the character.

\subsection{glutStrokeCharacter}

{\tt glutStrokeCharacter} renders a stroke character using OpenGL.

\subsubsection*{Usage}
\begin{verbatim}
void glutStrokeCharacter(void *font, int character);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt font]
Stroke font to use.
\item[\tt character]
Character to render (not confined to 8 bits).
\end{description}

\subsubsection*{Description}

Without using any display lists, {\tt glutStrokeCharacter} renders the {\tt character}
in the named stroke {\tt font}.  The available fonts are:
\begin{description}
\item[{\tt GLUT\_STROKE\_ROMAN}]
A proportionally spaced Roman Simplex font
for ASCII characters 32 through 127.  The maximum top character in the font
is 119.05 units; the bottom descends 33.33 units.

\item[{\tt GLUT\_STROKE\_MONO\_ROMAN}]
A mono-spaced spaced Roman Simplex font (same characters as {\tt GLUT\_STROKE\_ROMAN})
for ASCII characters 32 through 127.  The maximum top character in the font
is 119.05 units; the bottom descends 33.33 units.  Each character is 104.76
units wide.
\end{description}

Rendering a nonexistent character has no effect.  A {\tt glTranslatef} is used
to translate the current model view matrix to advance the width of the
character.

\section{Geometric Shape Rendering}

GLUT includes a number of routines for generating easily recognizable geometric
shapes.  These routines reflect functionality available in the {\tt aux} toolkit
and are included in GLUT to allow the construction of simple GLUT programs that
render recognizable objects.  These routines can be implemented as pure OpenGL
rendering routines.
The routines do {\em not} generate display lists for the objects they create.

The routines generate normals appropriate for lighting but do not generate
texture coordinates (except for the teapot).

\subsection{glutSolidSphere, glutWireSphere}

{\tt glutSolidSphere} and {\tt glutWireSphere} render a solid or wireframe
sphere respectively.

\subsubsection*{Usage}
\begin{verbatim}
void glutSolidSphere(GLdouble radius,
                     GLint slices, GLint stacks);
void glutWireSphere(GLdouble radius,
                    GLint slices, GLint stacks);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt radius]
The radius of the sphere.
\item[\tt slices]
The number of subdivisions around the Z axis (similar to lines of longitude).
\item[\tt stacks]
The number of subdivisions along the Z axis (similar to lines of latitude).
\end{description}

\subsubsection*{Description}

Renders a sphere centered at the modeling coordinates origin of the specified {\tt radius}.
The sphere is subdivided around the Z axis into slices and along the Z
axis into stacks.

\subsection{glutSolidCube, glutWireCube}

{\tt glutSolidCube} and {\tt glutWireCube} render a solid or wireframe
cube respectively.

\subsubsection*{Usage}
\begin{verbatim}
void glutSolidCube(GLdouble size);
void glutWireCube(GLdouble size);
\end{verbatim}

\subsubsection*{Description}

{\tt glutSolidCube} and {\tt glutWireCube} render a solid or wireframe
cube respectively.
The cube is centered at the modeling coordinates origin with sides of length {\tt size}.

\subsection{glutSolidCone, glutWireCone}

{\tt glutSolidCone} and {\tt glutWireCone} render a solid or wireframe
cone respectively.

\subsubsection*{Usage}
\begin{verbatim}
void glutSolidCone(GLdouble base, GLdouble height,
                   GLint slices, GLint stacks);
void glutWireCone(GLdouble base, GLdouble height,
                  GLint slices, GLint stacks);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt base]
The radius of the base of the cone.
\item[\tt height]
The height of the cone.
\item[\tt slices]
The number of subdivisions around the Z axis.
\item[\tt stacks]
The number of subdivisions along the Z axis.
\end{description}

\subsubsection*{Description}

{\tt glutSolidCone} and {\tt glutWireCone} render a solid or wireframe
cone respectively oriented along the Z axis.  The base of the cone
is placed at Z = 0, and the top at Z = {\tt height}.  The cone is subdivided
around the Z axis into slices, and along the Z axis into stacks.

\subsection{glutSolidTorus, glutWireTorus}

{\tt glutSolidTorus} and {\tt glutWireTorus} render a solid or wireframe
torus (doughnut) respectively.

\subsubsection*{Usage}
\begin{verbatim}
void glutSolidTorus(GLdouble innerRadius,
                    GLdouble outerRadius,
                    GLint nsides, GLint rings);
void glutWireTorus(GLdouble innerRadius,
                   GLdouble outerRadius,
                   GLint nsides, GLint rings);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt innerRadius]
Inner radius of the torus.
\item[\tt outerRadius]
Outer radius of the torus.
\item[\tt nsides]
Number of sides for each radial section.
\item[\tt rings]
Number of radial divisions for the torus.
\end{description}

\subsubsection*{Description}

{\tt glutSolidTorus} and {\tt glutWireTorus} render a solid or wireframe
torus (doughnut) respectively centered at the modeling coordinates origin whose axis is aligned
with the Z axis.

\subsection{glutSolidDodecahedron, glutWireDodecahedron}

{\tt glutSolidDodecahedron} and {\tt glutWireDodecahedron} render a solid or wireframe
dodecahedron (12-sided regular solid) respectively.

\subsubsection*{Usage}
\begin{verbatim}
void glutSolidDodecahedron(void);
void glutWireDodecahedron(void);
\end{verbatim}

\subsubsection*{Description}

{\tt glutSolidDodecahedron} and {\tt glutWireDodecahedron} render a solid or wireframe
dodecahedron respectively centered at the modeling coordinates origin with a radius of $\sqrt{3}$.

\subsection{glutSolidOctahedron, glutWireOctahedron}

{\tt glutSolidOctahedron} and {\tt glutWireOctahedron} render a solid or
wireframe octahedron (8-sided regular solid) respectively.

\subsubsection*{Usage}
\begin{verbatim}
void glutSolidOctahedron(void);
void glutWireOctahedron(void);
\end{verbatim}

\subsubsection*{Description}

{\tt glutSolidOctahedron} and {\tt glutWireOctahedron} render a solid or
wireframe octahedron respectively centered at the modeling coordinates origin with a radius of 1.0.

\subsection{glutSolidTetrahedron, glutWireTetrahedron}

{\tt glutSolidTetrahedron} and {\tt glutWireTetrahedron} render a solid or wireframe
tetrahedron (4-sided regular solid) respectively.

\subsubsection*{Usage}
\begin{verbatim}
void glutSolidTetrahedron(void);
void glutWireTetrahedron(void);
\end{verbatim}

\subsubsection*{Description}

{\tt glutSolidTetrahedron} and {\tt glutWireTetrahedron} render a solid or wireframe
tetrahedron respectively centered at the modeling coordinates origin with a radius of $\sqrt{3}$.

\subsection{glutSolidIcosahedron, glutWireIcosahedron}

{\tt glutSolidIcosahedron} and {\tt glutWireIcosahedron} render a solid or wireframe
icosahedron (20-sided regular solid) respectively.

\subsubsection*{Usage}
\begin{verbatim}
void glutSolidIcosahedron(void);
void glutWireIcosahedron(void);
\end{verbatim}

\subsubsection*{Description}


{\tt glutSolidIcosahedron} and {\tt glutWireIcosahedron} render a solid or wireframe
icosahedron respectively.  The icosahedron is centered at the modeling coordinates origin and has a radius
of 1.0.

\subsection{glutSolidTeapot, glutWireTeapot}

{\tt glutSolidTeapot} and {\tt glutWireTeapot} render a solid or wireframe
teapot respectively.

\subsubsection*{Usage}
\begin{verbatim}
void glutSolidTeapot(GLdouble size);
void glutWireTeapot(GLdouble size);
\end{verbatim}
\begin{description}
\itemsep 0in
\item[\tt size] Relative size of the teapot.
\end{description}

\subsubsection*{Description}

{\tt glutSolidTeapot} and {\tt glutWireTeapot} render a solid or wireframe
teapot respectively centered at the modeling coordinates origin.  Normals
coordinates are automatically generated.

\section{Usage Advice}

Do not change state that will affect the way a window
will be drawn in a window's display callback.
Your display callback should be idempotent.

If you need to redisplay a window, instead of rendering in
whatever callback you happen to be in, call {\tt glutPostRedisplay}.
As a general rule, the only code that renders directly to the screen
should be in called from display callbacks; other types of callbacks
should not be rendering to the screen.

If you use an idle callback to control your animation, use the
visibility callbacks to determine when the window is fully obscured
or iconified to determine when not to waste processor time rendering.

Avoid using color index mode if possible.

For most callbacks, the {\em current window} and/or {\em current menu} is
set appropriately at the time of the callback.  Timer and idle callbacks
are exceptions.  If your application uses multiple windows or menus,
make sure in idle and timer callback you explicitly set the
window or menu appropriately using {\tt glutSetWindow} and {\tt
glutSetMenu}.

By default, timer and idle callbacks may be called while a
pop-up menu is active.  On slow machines, slow rendering in an idle
callback may compromise menu performance.  Also, it may be desirable
for motion to stop immediately when a menu is triggered.  In this
case, use the menu entry/exit callback set with {\tt glutMenuStateFunc}
to track the usage of pop-up menus.

Do not select for more input callbacks than you actually
need.  For example, if you do not need motion or passive motion
callbacks, disable them by passing {\tt NULL} to their callback
register functions.  Disabling input callbacks allows the GLUT
implementation to limit the window system input events that must
be processed.

Not every OpenGL implementation supports the same range of
frame buffer capabilities though minimum requirements for
frame buffer capabilities do exist.  If {\tt glutCreateWindow}
or {\tt glutCreateSubWindow} are called with an {\em initial
display mode} not supported by the OpenGL implementation,
a fatal error will be generated with an explanatory message.
To avoid this, {\tt glutGet(GLUT\_DISPLAY\_MODE\_POSSIBLE)}
should be called to determine if the {\em initial
display mode} is supported by the OpenGL implementation.

\section{FORTRAN Binding}

All GLUT functionality is available through the GLUT \Fortran\ API.
The GLUT \Fortran\ binding is intended to be used in conjunction with the OpenGL and GLU
\Fortran\ APIs.

A \Fortran\ routine using GLUT routines should include the GLUT \Fortran\
header file.  While this is potentially system dependent, on Unix
systems this is normally done by including after the {\tt SUBROUTINE},
{\tt FUNCTION}, or {\tt PROGRAM} line:
\begin{verbatim}
#include "GL/fglut.h"
\end{verbatim}

The GLUT \Fortran\ binding (and the OpenGL and GLU \Fortran\ bindings)
assume identifiers are not limited to 6 characters.

\subsection{Names for the FORTRAN GLUT Binding}

Allowing for {\sc Fortran}'s case-insensitivity, the GLUT \Fortran\ binding
constant and routine names are the same as the C binding's names.

The ARB's official OpenGL \Fortran\ API prefixes every routine and
constant with the letter F.  The justification was to avoid name
space collisions with the C names in anachronistic compilers.  Nearly
all modern \Fortran\ compilers avoid these name space clashes via other
means (underbar suffixing of \Fortran\ routines is used by most Unix \Fortran\
compilers).

The GLUT \Fortran\ API does {\em not} use such prefixing conventions
because of the documentation and coding confusion introduced by
such prefixes.  The confusion is heightened by
{\sc Fortran}'s default implicit variable initialization so programmers
may realize the lack of a constant prefix as a result of a run-time error.
The confusion introduced to support the prefixes
was not deemed worthwhile simply to support anachronistic
compliers.

The OpenGL ARB's official \Fortran\ binding for the GLU and OpenGL APIs
that chose to prefix the letter {\tt F} before every OpenGL and GLU
constant and routine name.  

\subsection{Font Naming Caveat}

Because GLUT fonts are compiled directly into GLUT programs as data,
and programs should only have the fonts compiled into them that they use,
GLUT font names like {\tt GLUT\_BITMAP\_TIMES\_ROMAN\_24} are really
symbols so the linker should only pull in used fonts.

Unfortunately, because some supposedly modern \Fortran\ compilers
link declared but unused data EXTERNALs, ``GL/fglut.h'' does not
explicitly declare EXTERNAL the GLUT font symbols.  Declaring the
GLUT font symbols as 
EXTERNAL risks forcing every GLUT \Fortran\
program to contain the data for every GLUT font.  GLUT
Fortran programmers should explicitly declare EXTERNAL
the GLUT fonts they use.  Example:
\begin{verbatim}
        SUBROUTINE PRINTA
#include "GL/fglut.h"
        EXTERNAL GLUT_BITMAP_TIMES_ROMAN_24
        CALL glutBitmapCharacter(GLUT_BITMAP_TIMES_ROMAN_24, 65)
        END
\end{verbatim}

\subsection{NULL Callback}

\Fortran\ does not support passing {\tt NULL} as a callback
parameter the way ANSI C does.  For this reason, {\tt GLUTNULL}
is used in place of {\tt NULL} in GLUT \Fortran\ programs to
indicate a {\tt NULL} callback.

\section{Implementation Issues}

While this specification is primarily intended to describe the GLUT API
and not its implementation, the section describes implementation
issues that are likely to help both GLUT implementors properly
implement GLUT and provide GLUT programmers with information to better
utilize GLUT.

\subsection{Name Space Conventions}

The GLUT implementation should have a well-defined name space for both
exported symbols and visible, but not purposefully exported symbols.
All exported functions are prefixed by {\tt glut}.  All exported macro
definitions are prefixed by {\tt GLUT\_}.  No data symbols are
exported.  All internal symbols that might be user-visible but not
intended to be exported should be prefixed by {\tt \_\_glut}.  Users of
the GLUT API should {\em not} use any {\tt \_\_glut} prefixed symbols.

\newpage

\appendix

%\mbox{}\\
%\vspace{1.5in}

\section{GLUT State}

This appendix specifies precisely what programmer visible state GLUT
maintains.  There are three categories of programmer visible state GLUT
maintains:  global, window, and menu.  The window and menu state categories
are maintained for each created window or menu.

The tables below name each element of state, define its type, specify
what GLUT API entry points set or change the state (if possible), specify what GLUT API
entry point or {\tt glutGet} state constant is used to get the state (if possible),
and how the state is initially set.  For details of how any API entry point
operates on the specified state, see the routine's official description.
Notes for each category of state indicate additional caveats to the element
of state.

\subsection{Types of State}

The programmer visible state maintained by GLUT is of varying types:
\begin{description}

\item[\em BitMask]
A group of boolean bits.

\item[\em Boolean]
True or false.

\item[\em Callback]
A handle to a user-supplied routine invoked when the given callback is triggered
(or {\tt NULL} which is the default callback).

\item[\em ColorCell]
Red, green, and blue color component triple, an array of which makes
a colormap.

\item[\em Integer]
An integer value.

\item[\em MenuItem]
Either a menu entry or a submenu trigger.  Both subtypes contain
of a {\em String} name.  A menu entry has an {\em Integer} value.  A
submenu cascade has an {\em Integer} menu name naming its associated submenu.

\item[\em Stacking]
An ordering for top-level windows and sub-windows having the same
parent.  Higher windows obscure lower windows.

\item[\em State]
One of shown, hidden, or iconified.

\item[\em String]
A string of ASCII characters.

\item[\em Timer]
A triple of a timer {\em Callback}, an {\em Integer} callback parameter, and a time
in milliseconds (that expires in real time).

\end{description}

%\newsavebox{\globalstate}

\subsection{Global State}

{\tiny
\begin{tabular}{|l|l|l|l|l|} \hline
Name & Type & Set/Change & Get & Initial \\ \hline
currentWindow & Integer & glutSetWindow \takeNote & glutGetWindow & 0 \\
currentMenu & Integer & glutSetMenu \takeNote & glutGetMenu & 0 \\
initWindowX & Integer & glutInitWindowPosition & GLUT\_INIT\_WINDOW\_X & -1 \\
initWindowY & Integer & glutInitWindowPosition & GLUT\_INIT\_WINDOW\_Y & -1 \\
initWindowWidth & Integer & glutInitWindowSize & GLUT\_INIT\_WINDOW\_WIDTH & 300 \\
initWindowHeight & Integer & glutInitWindowSize & GLUT\_INIT\_WINDOW\_HEIGHT & 300 \\
initDisplayMode & BitMask & glutInitDisplayMode & GLUT\_INIT\_DISPLAY\_MODE & GLUT\_RGB, \\
& & & & GLUT\_SINGLE, \\
& & & & GLUT\_DEPTH \\
idleCallback & Callback & glutIdleFunc & - & NULL \\
menuStateCallback & Callback & glutMenuEntryFunc & - & NULL \\
timerList & list of Timer & glutTimerFunc & - & none \\
screenWidth & Integer & - & GLUT\_SCREEN\_WIDTH & system dependent \\
screenHeight & Integer & - & GLUT\_SCREEN\_HEIGHT & system dependent \\
screenWidthMM & Integer & - & GLUT\_SCREEN\_WIDTH\_MM & system dependent \\
screenHeightMM & Integer & - & GLUT\_SCREEN\_HEIGHT\_MM & system dependent \\
\hline
\end{tabular}
}

\resetNote

{\footnotesize
\begin{description}
\itemsep 0in
\item[\takeNote] The currentWindow is also changed implicitly by every window
callback (to the window triggering the callback) and the creation of a window
(to the window being created).
\item[\takeNote] The currentMenu is also changed implicitly by every menu
callback (to the menu triggering the callback) and the creation of a menu
(to the menu being created).
\end{description}
}

%\input rotate.tex
%\def\myrotr#1{\rotdimen=\ht#1\advance\rotdimen by\dp#1%
%   \hbox to\rotdimen{\vbox to\wd#1{\vskip\wd#1%
%   \rotstart{270 rotate}%
%\box#1\vss}\hss}\rotfinish}%
%
%\newbox\thebox
%
%\setbox\thebox=\vbox{\usebox{\globalstate}}
%
%\myrotr\thebox

\subsection{Window State}

For the purposes of listing the window state elements, window state is
classified into two types:  generic state and frame buffer capability state.
The tags {\em top-level}, {\em sub-win}, and {\em cindex} indicate the
table entry applies only to top-level windows, subwindows, or color index
windows respectively.

\subsubsection{Generic State:}

\resetNote
{\tiny
\begin{tabular}{|l|l|l|l|l|} \hline
Name & Type & Set/Change & Get & Initial \\ \hline
number & Integer & - & glutGetWindow & {\em top-level:} glutCreateWindow \takeNote \\
& & & & {\em sub-win:} glutCreateSubWindow \sameNote \\
x & Integer & glutPositionWindow & GLUT\_WINDOW\_X & {\em top-level:} initWindowX \takeNote \\
& & & & {\em sub-win:} glutCreateSubWindow \\
y & Integer & glutPositionWindow & GLUT\_WINDOW\_Y & {\em top-level:} initWindowY \takeNote \\
& & & & {\em sub-win:} glutCreateSubWindow \\
width & Integer & glutReshapeWindow & GLUT\_WINDOW\_WIDTH & {\em top-level:} initWindowWidth \takeNote \\
& & & & {\em sub-win:} glutCreateSubWindow \\
height & Integer & glutReshapeWindow & GLUT\_WINDOW\_HEIGHT & {\em top-level:} initWindowHeight \takeNote \\
& & & & {\em sub-win:} glutCreateSubWindow \\
stacking & Stacking & glutPopWindow & - & top \\
& & glutPushWindow & & \\
displayState & State \takeNote & glutShowWindow \takeNote & - & shown \\
& & glutHideWindow & & \\
& & glutIconifyWindow & & \\
visibility & Visibility & \takeNote & \takeNote & undefined \\
redisplay & Boolean & glutPostRedisplay \takeNote & - & False \\
toplevel: windowTitle & String & glutWindowTitle & - & glutCreateWindow \\
toplevel: iconTitle & String & glutIconTitle & - & glutCreateWindow \\
displayCallback & Callback & glutDisplayFunc & - & NULL \\
reshapeCallback & Callback & glutReshapeFunc & - & NULL \takeNote \\
keyboardCallback & Callback & glutKeyboardFunc & - & NULL \\
mouseCallback & Callback & glutMouseFunc & - & NULL \\
motionCallback & Callback & glutMotionFunc & - & NULL \\
passiveMotionCallback & Callback & glutPassiveMotionFunc & - & NULL \\
visibilityCallback & Callback & glutVisibilityFunc & - & NULL \\
entryCallback & Callback & glutEntryFunc & - & NULL \\
{\em cindex:} colormap & array of & glutSetColor & glutGetColor & undefined \\
& ColorCell & & & \\
windowParent & Integer & - & GLUT\_WINDOW\_PARENT & {\em top-level:} 0 \\
& & & & {\em sub-win:} \takeNote \\
numChildren & Integer & glutCreateSubWindow & GLUT\_NUM\_CHILDREN & 0 \\
& & glutDestroyWindow & & \\
& & glutCopyColormap & & \\
leftMenu & Integer & glutAttachMenu & - & 0 \\
& & glutDetachMenu & & \\
middleMenu & Integer & glutAttachMenu & - & 0 \\
& & glutDetachMenu & & \\
rightMenu & Integer & glutAttachMenu & - & 0 \\
& & glutDetachMenu & & \\
\hline
\end{tabular}
}

\resetNote

{\footnotesize
\begin{description}
\itemsep 0in
\item[\takeNote]  Assigned dynamically from unassigned window numbers greater than zero.
\item[\takeNote]  If initWindowX is greater or equal to zero {\em and}
initWindowY is greater or equal to zero then initWindowX, else
window location left to window system to decide.
\item[\takeNote]  If initWindowY is greater or equal to zero {\em and}
initWindowX is greater or equal to zero then initWindowY, else
window location left to window system to decide.
\item[\takeNote]  If initWindowWidth is greater than zero {\em and} initWindowHeight is greater than zero
the initWindowWidth, else
window size left to window system to decide.
\item[\takeNote]  If initWindowHeight is greater than zero {\em and} initWindowWidth is greater than zero
then initWindowHeight, else
window size left to window system to decide.
\item[\takeNote]  Subwindows can not be iconified.
\item[\takeNote]  Window system events can also change the displayState.
\item[\takeNote]  Visibility of a window can change for window system dependent reason, for
  example, a new window may occlude the window.  glutPopWindow and glutPushWindow can
  affect window visibility as a side effect.
\item[\takeNote]  The visibility callback set by glutVisibilityFunc allows the visibility state to be tracked.
\item[\takeNote]  The redisplay state can be explicitly enabled by glutRedisplayFunc or
  implicitly in response to redisplay events from the window system.
\item[\takeNote]  Instead of being a no-op as most NULL callbacks are, a NULL reshapeCallback
sets the OpenGL viewport to render into the complete window, ie. {\tt glViewport(0,0,width, height)}.
\item[\takeNote]  Determined by currentWindow at glutCreateSubWindow time.
\end{description}
}

\subsubsection{Frame Buffer Capability State:}

\resetNote
{\tiny
\begin{tabular}{|l|l|l|} \hline
Name & Type & Get \\ \hline
Total number of bits in color buffer & Integer & GLUT\_WINDOW\_BUFFER\_SIZE \\
Number of bits in stencil buffer & Integer & GLUT\_WINDOW\_STENCIL\_SIZE \\
Number of bits in depth buffer & Integer & GLUT\_WINDOW\_DEPTH\_SIZE \\
Number of bits of red stored in color buffer & Integer & GLUT\_WINDOW\_RED\_SIZE \\
Number of bits of green stored in color buffer & Integer & GLUT\_WINDOW\_GREEN\_SIZE \\
Number of bits of blue stored in color buffer & Integer & GLUT\_WINDOW\_BLUE\_SIZE \\
Number of bits of alpha stored in color buffer & Integer & GLUT\_WINDOW\_ALPHA\_SIZE \\
Number of bits of red stored in accumulation buffer & Integer & GLUT\_WINDOW\_ACCUM\_RED\_SIZE \\
Number of bits of green stored in accumulation buffer & Integer & GLUT\_WINDOW\_ACCUM\_GREEN\_SIZE \\
Number of bits of blue stored in accumulation buffer & Integer & GLUT\_WINDOW\_ACCUM\_BLUE\_SIZE \\
Number of bits of alpha stored in accumulation buffer & Integer & GLUT\_WINDOW\_ACCUM\_ALPHA\_SIZE \\
Color index colormap size & Integer & GLUT\_WINDOW\_COLORMAP\_SIZE \\
If double buffered & Boolean & GLUT\_WINDOW\_DOUBLEBUFFER \\
If RGBA color model & Boolean & GLUT\_WINDOW\_RGBA \\
\hline
\end{tabular}
}

A window's frame buffer capability state is derived from the global initDisplayMode
state at the window's creation.  A window's frame buffer capabilities can not
be changed.

\subsection{Menu State}

\resetNote

{\tiny
\begin{tabular}{|l|l|l|l|l|} \hline
Name & Type & Set/Change & Get & Initial \\ \hline
number & Integer & - & glutSetMenu & {\em top-level:} glutCreateMenu \takeNote \\
select & Callback & - & - & glutCreateMenu \\
items & list of MenuItem & - & - & - \\
numItems & Integer & - & GLUT\_MENU\_NUM\_ITEMS & 0 \\
\hline
\end{tabular}
}
\resetNote

{\footnotesize
\begin{description}
\itemsep 0in
\item[\takeNote]  Assigned dynamically from unassigned window numbers greater than zero.
\end{description}
}

\section{glut.h ANSI C Header File}

{\footnotesize
\verbatimlisting{glut.h.notab}
}

\section{fglut.h FORTRAN Header File}

{\footnotesize
\verbatimlisting{fglut.h.notab}
}

\newpage

\addcontentsline{toc}{section}{References}

\begin{thebibliography}{99}

\bibitem{karlton93} Phil Karlton, {\em OpenGL Graphics with the X
Window System}, Ver. 1.0, Silicon Graphics, April 30, 1993.

\bibitem{kilgard93}
Mark Kilgard, ``Programming X Overlay Windows,'' {\em The X Journal},
SIGS Publications, July 1993.

\bibitem{kilgard94a}
Mark Kilgard, ``OpenGL and X, Part 2: Using OpenGL with Xlib,''
{\em The X Journal}, SIGS Publications, Jan/Feb 1994.

\bibitem{kilgard94b}
Mark Kilgard, ``OpenGL and X, Part 3: Integrating OpenGL with Motif,''
{\em The X Journal}, SIGS Publications, Jul/Aug 1994.

\bibitem{kilgard94c}
Mark Kilgard, ``An OpenGL Toolkit,''
{\em The X Journal}, SIGS Publications, Nov/Dec 1994.

\bibitem{neider93}
Jackie Neider, Tom Davis, Mason Woo, {\em OpenGL Programming Guide:
The official guide to learning OpenGL, Release 1}, Addison Wesley, 1993.

\bibitem{arb92}
OpenGL Architecture Review Board, {\em OpenGL Reference Manual:  The
official reference document for OpenGL, Release 1}, Addison Wesley, 1992.

\bibitem{x92}
Robert Scheifler, James Gettys, {\em X Window System: The complete Reference
to Xlib, X Protocol, ICCCM, XLFD}, third edition, Digital Press, 1992.

\bibitem{segal92}
Mark Segal, Kurt Akeley, {\em The OpenGL${}^{\rm TM}$ Graphics System:
A Specification}, Version 1.0, Silicon Graphics, June 30, 1992.

\bibitem{sgi91a}
Silicon Graphics, {\em Graphics Library Programming Guide},
Document Number 007-1210-040, 1991.

\bibitem{sgi91b}
Silicon Graphics, {\em Graphics Library Window and Font Library Guide},
Document Number 007-1329-010, 1991.

\end{thebibliography}

\end{document}

